<?php
/**
 * Celebrio FileSystem module
 *
 * @copyright  Copyright (c) 2011 Celebrio Software
 * @package    Celebrio
 * @subpackage FileSystem
 */
namespace Celebrio\FileSystem;

use Celebrio\FileSystem\DataFile;

/**
 * VirtualFileSystem API. It is used by implementation of IFileSystem.
 * 
 * It provides simple interface for calling the file operations.
 * Every file is represented as DataFile object, but some attributes 
 * may be uninitialized (for example when trying to open the file,
 * we don't know it's size or data yet).
 *
 * @author pavel
 */
interface IVirtualFileSystem {


/* -------------------------------------------------------------------------- */
/* -------------------------------------------------------------------------- */
/* ----------------- DATA MANIPULATING FUNCTIONS ---------------------------- */
/* -------------------------------------------------------------------------- */
/* -------------------------------------------------------------------------- */


    /**
     * Loads the file content from the storage. It includes checking
     * permissions, the database operations (for example logging) and
     * low-level driver operations which loads the file content itself.
     * When error occurs, exception is thrown.
     *
     * @param DataFile $file structure specifying the URL and name of the file.
     *      The mimetype attribute can be also mentioned but it's ignored
     *      (and will be as far as we trust only our DB, not foreign
     *      applications).
     * @param bool $stream if data should be streamed. It is true when 
     *      streaming is required and false when it is necesary to store data
     *      to server memory.
     * @return DataFile the file with assigned mimetype and content
     *      (data). If the given (i.e required) entry is regular file,
     *      $file->data contains the binary content of the file.
     *      When $file parameter is recognized as directory, the result
     *      $file->data contains the array of child files/subdirectories.
     *      Each of them is represented as VirtualFile ('coz we have to
     *      specify also attributes and so on).
     *
     * @throws Exception when something screws up
     *      //TODO specify the possible Exception types
     *      (for now it's anyway only feed for the Nette\Debug monster).
     */
    function load(DataFile $file, $stream = false);

    function getFileInfo(DataFile $file);

    /**
     * Saves the file content to the disk. If the file does not exist
     * and the current user has permissions to create it, it's created.
     * Missing directories in the path are created as well, if necessary.
     * When error occurs, exception is thrown. This method also checks
     * the access rights (writing).
     *
     * @param DataFile $file structure specifying the URL and name
     *      of the file.
     *
     * @throws Exception //TODO specify tye possible Exception types
     */
    function save(DataFile $file);

    

/* -------------------------------------------------------------------------- */
/* -------------------------------------------------------------------------- */
/* ----------------- FILE MANIPULATING FUNCTIONS ---------------------------- */
/* -------------------------------------------------------------------------- */
/* -------------------------------------------------------------------------- */

    /**
     * Moves the file or directory (with all sub-directories and files). Also
     * checks the permissions.
     *
     * Note: If you specify different mimetype in $target, it's ignored.
     * To be honest, the mimetype is ignored at all by this method.
     * 
     * @param VirtualFile $source
     * @param VirtualFile $target
     * @param boolean $rewrite
     *
     * @throws Exception when error occurs
     */
    function move(DataFile $source, DataFile $target, $rewrite);

    /**
     * Deletes the given File from DB including all
     * child-entries. The files you don't have permission
     * to delete are skipped and their parents as well
     * (the path must be kept).
     *
     * @param DataFile $file
     *
     * @throws Exception when error occurs
     */
    function delete(DataFile $file);

    /**
     * Copies the file or folder (including content) to another
     * location. Also checks permission while both reading
     * from the source location and writing to the target destination.
     * Only the files you have permission to copy are really copied.
     *
     * @param DataFile $from
     * @param DataFile $to
     * @param boolean $rewrite Specifies whether possibly existing
     *          files in the target location (directory) should be rewritten.
     */
    function copy(DataFile $source, DataFile $target, $rewrite);


/* -------------------------------------------------------------------------- */
/* -------------------------------------------------------------------------- */
/* -------------- PERMISSION MANIPULATING FUNCTIONS ------------------------- */
/* ------------------- (maybe other interface?) ----------------------------- */
/* -------------------------------------------------------------------------- */

    //TODO permissions changes methods


/* -------------------------------------------------------------------------- */
/* -------------------------------------------------------------------------- */
/* ------------------- OWNER CHANGING FUNCTIONS ----------------------------- */
/* ------------------- (maybe other interface?) ----------------------------- */
/* -------------------------------------------------------------------------- */

    //TODO change owner methods

}
